home *** CD-ROM | disk | FTP | other *** search
/ The Arsenal Files 8 / The Arsenal Files Collection #8 (Arsenal Computer) (1996).ISO / prg_casm / wsc4c10.zip / WSC4C_U.DOC < prev    next >
Text File  |  1996-09-09  |  47KB  |  1,429 lines
  1.  
  2.  
  3.                  Windows Standard Communications
  4.  
  5.                         Library for C/C++
  6.  
  7.                              (WSC4C)
  8.  
  9.  
  10.                           USERS MANUAL
  11.  
  12.  
  13.  
  14.                             Version 1.0
  15.  
  16.                            September 9, 1996
  17.  
  18.  
  19.  
  20.  
  21.                  This software is provided as-is.
  22.           There are no warranties, expressed or implied.
  23.  
  24.  
  25.  
  26.  
  27.                        Copyright (C) 1996
  28.                        All rights reserved
  29.  
  30.  
  31.  
  32.                    MarshallSoft Computing, Inc.
  33.                        Post Office Box 4543
  34.                        Huntsville AL 35815
  35.  
  36.                        Voice : 205-881-4630
  37.                          FAX : 205|880|0925
  38.                          BBS : 205-880-9748
  39.                        email : info@marshallsoft.com
  40.                          web : www.marshallsoft.com
  41.  
  42.                            _______
  43.                       ____|__     |                (R)
  44.                    --+       |    +-------------------
  45.                      |   ____|__  |  Association of
  46.                      |  |       |_|  Shareware
  47.                      |__|   o   |    Professionals
  48.                    --+--+   |   +---------------------
  49.                         |___|___|    MEMBER
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  WSC4C Users Manual                                                Page 1
  69.                        C O N T E N T S
  70.  
  71.  
  72.  
  73.  
  74.  
  75.   Chapter                                                   Page
  76.  
  77.   1.0 Introduction................................................3
  78.       1.1 User Support............................................4
  79.       1.2 ASP Ombudsman...........................................4
  80.       1.3 Determining UART Address & IRQ Settings.................5
  81.       1.4 Installation............................................6
  82.   2.0 [reserved chapter]
  83.   3.0 Library Overview............................................7
  84.       3.1 Dynamic Link Libraries..................................7
  85.       3.2 Using the Library.......................................7
  86.       3.3 Compiling Programs......................................7
  87.       3.4 Using a Makefile........................................7
  88.       3.5 Using an IDE............................................8
  89.       3.6 Compiling WSC...........................................8
  90.   4.0 Talking to Your Modem.......................................9
  91.       4.1 Modem Standards.........................................9
  92.       4.2 Flow Control...........................................10
  93.       4.3 Modem I/O Functions....................................11
  94.       4.4 Modem Initialization...................................13
  95.   5.0 Problems...................................................14
  96.   6.0 Serial Communications......................................15
  97.       6.1 Communications Basics..................................15
  98.       6.2 RS232 Signals..........................................15
  99.   7.0 Example Programs...........................................17
  100.       7.1 SIMPLE.................................................17
  101.       7.2 LOGIN..................................................17
  102.       7.3 SELFTEST...............................................17
  103.       7.4 RS232..................................................17
  104.   8.0 Legal Issues...............................................18
  105.       8.1 Registration...........................................18
  106.       8.2 License................................................19
  107.       8.3 Warranty...............................................19
  108.   9.0 Summary....................................................20
  109.       9.1 Revision History.......................................19
  110.       9.2 Function Summary.......................................20
  111.       9.3 Further Reading........................................21
  112.  10.0 Other MarshallSoft Computing products for C/C++............21
  113.       10.1 Personal Communications Library for Windows...........21
  114.       10.2 Personal Communications Library for C/C++.............21
  115.       10.3 Libraries for Other Languages.........................21
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  WSC4C Users Manual                                                Page 2
  137.   1.0 Introduction
  138.  
  139.  
  140.   The  Windows  Standard  Communications  Library  for  C/C++  (WSC4C)  is an
  141.   asynchronous communications (16-bit) dynamic link library (DLL)  which  uses
  142.   the  standard  Windows  serial communications API. Since it uses the Windows
  143.   API, programs using the WSC library are fully compatible with  other  Window
  144.   applications which also use the Windows serial communications API.
  145.  
  146.   Using  WSC  is  very  straight-forward. For example, to write "HELLO" to the
  147.   serial port COM1:
  148.  
  149.       SioReset(COM1,128,128)    /* open COM1 */
  150.       SioPuts(COM1,"HELLO",5)   /* write "HELLO" to COM1 */
  151.       SioDone(COM1)             /* close COM1 */
  152.  
  153.   Four  C/C++  example  programs with full source code are included. Refer to
  154.   chapter 7 for more details on each of the example programs.
  155.  
  156.       SIMPLE : A simple terminal emulator.
  157.  
  158.        LOGIN : Same as SIMPLE but can also dial a modem and log onto a BBS.
  159.  
  160.     SELFTEST : Performs COM port functionality testing.
  161.  
  162.        RS232 : Same as SIMPLE but controls flow control, modem lines, etc.
  163.  
  164.   WSC4C contains over 25 functions. All functions return a negative number  if
  165.   an  error  condition  is  detected.   For  more  details,  consult the WSC4C
  166.   Reference Manual
  167.  
  168.   WSC4C uses the same function names  and  arguments  as  PCL4W  (our  Windows
  169.   Communications  Library  that does NOT use the Windows API) except for a few
  170.   functions.
  171.  
  172.   Our goal is to provide a robust serial communications library that that  you
  173.   and your customers can depend upon. Contact us if you have any questions.
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.  
  203.  
  204.  WSC4C Users Manual                                                Page 3
  205.   1.1 User Support
  206.  
  207.  
  208.   We want you to be successful in developing your applications using WSC4C! We
  209.   depend  upon our customers to let us know what they need in a communications
  210.   library.  This means we are committed to providing the  best  communications
  211.   library  that we can. If you have any suggestions or comments, please let us
  212.   know.
  213.  
  214.   If you are having a problem using WSC4C, call  us  at  205-881-4630  between
  215.   1:30PM  and  9:30PM  CST  Monday  through Friday. You can also call at other
  216.   times and leave a message, and call back  later  for  a  reply.   Registered
  217.   users (ONLY) can also FAX us at 205-880-0925 at any time (24 hours).
  218.  
  219.   However,  we  can  only  answer  questions  with  respect to using the WSC4C
  220.   library.  We cannot help you program your application.
  221.  
  222.   You may also call our User Support BBS (2400 to 14400  baud,  no  parity,  8
  223.   data  bits,  1  stop bit) at 205-880-9748 and leave a message (address it to
  224.   the SYSOP).  We will usually have a reply ready for you within 24 hours.
  225.  
  226.   The BBS  is  available  24  hours  per  day  except  at  2  PM  Sundays  for
  227.   maintenanace. All files are in standard ZIP format. The BBS will contain the
  228.   latest  shareware  version  of  all MarshallSoft products as well as related
  229.   files such as:
  230.  
  231.        BUGS.ZIP:  Bug report.
  232.        NEWS.ZIP:  Latest news regarding our products.
  233.  
  234.   If you are on the Internet, you can email us at info@marshallsoft.com.   You
  235.   can  also  get  the  latest  versions of our products from our anonymous ftp
  236.   site:
  237.  
  238.         FTP:   ftp.marshallsoft.com
  239.        PATH:   marshallsoft
  240.  
  241.   The MarshallSoft  Computing,  Inc.   newsletter  "Comm  Talk"  is  published
  242.   quarterly.  It discusses various communications problems and solutions using
  243.   WSC4C as well as related information.
  244.  
  245.   The  latest  copy of our newsletter can be found on our User Support BBS (in
  246.   file area "Newsletters"), our anonymous ftp site  (directory  /marshallsoft)
  247.   as well as our web site.
  248.  
  249.       Web site:  www.marshallsoft.com
  250.  
  251.  
  252.   1.2 ASP Ombudsman
  253.  
  254.  
  255.   MarshallSoft  Computing,  Inc.   is a member of the Association of Shareware
  256.   Professionals (ASP).  ASP wants to make sure that  the  shareware  principle
  257.   works  for  you.   If  you are unable to resolve a shareware-related problem
  258.   with an ASP member by contacting the member directly, ASP  may  be  able  to
  259.   help.   The  ASP Ombudsman can help you resolve a dispute or problem with an
  260.   ASP member, but does not provide technical support  for  members'  products.
  261.   Please  write  to  the  ASP  Ombudsman  at 545 Grover Road, Muskegon, MI USA
  262.   49442-9427, Fax 616-788-2765, or send a CompuServe  message  via  CompuServe
  263.   Mail to ASP Ombudsman 70007,3536.
  264.  
  265.  
  266.  
  267.  
  268.  
  269.  
  270.  
  271.  
  272.  WSC4C Users Manual                                                Page 4
  273.   1.3 Determining UART Address & IRQ Settings
  274.  
  275.  
  276.   You  will  not  normally  need to know the port addresses or IRQ assignments
  277.   made by Windows. But this information  is  maintained  by  Windows,  and  is
  278.   available if you need it.
  279.  
  280.   Both Windows 3.X and Windows 95 maintain a list of serial port settings.  On
  281.   Windows  3.X  systems, choose the "Ports" icon in the "Control Panel" in the
  282.   "Main Group".  Select "Settings", and then "Advanced" to view the  COM  port
  283.   UART address and IRQ settings.
  284.  
  285.   In Windows 95, choose "My Computer" icon ("or whatever your computer icon is
  286.   named), select the "Control Panel" folder and then the "System" icon.  Click
  287.   on  the "Device Manager" tab.  Click "Computer" and then click "Properties".
  288.   Click the "View Resources" tab.   To  view  reserved  resources,  click  the
  289.   resource  type at the top of the dialog box (i.e., "Interrupt request (IRQ)"
  290.   or "Input/output (I/O)" ).
  291.  
  292.   The four standard COM ports which Windows typically controls are:
  293.  
  294.         Port  Address  IRQ
  295.         COM1   &H3F8    4
  296.         COM2   &H2F8    3
  297.         COM3   &H3E8    4
  298.         COM4   &H2E8    3
  299.  
  300.  
  301.  
  302.  
  303.  
  304.  
  305.  
  306.  
  307.  
  308.  
  309.  
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327.  
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334.  
  335.  
  336.  
  337.  
  338.  
  339.  
  340.  WSC4C Users Manual                                                Page 5
  341.   1.4 Installation
  342.  
  343.   This shareware product  may  be  evaluated  for  500  executions  (calls  to
  344.   SioReset). WSC4C must be installed using the TRIALS manager before it can be
  345.   executed. To install WSC4C:
  346.  
  347.   (1) Before installation of WSC4C, your Windows C/C++ compiler should already
  348.   be  installed on your system and tested.  Examine the file "FILES.LST" for a
  349.   list of the distribution files.
  350.  
  351.   (2) Make a backup  copy  of  your  distribution  disk.   Put  your  original
  352.   distribution disk in a safe place.
  353.  
  354.   (3) Exit Windows into DOS, or start a DOS window:
  355.  
  356.   (4) Create a work directory. For example, to create C:\WSC4C, type:
  357.  
  358.         C:
  359.         CD \
  360.         MKDIR WSC4C
  361.         CD WSC4C
  362.  
  363.   (5) Unzip all distribution files to your working directory.
  364.  
  365.         PKUNZIP WSC4C10.ZIP
  366.  
  367.   If  this  is  a  "Commercial"  registered  version,  skip  to  step 10.  The
  368.   shareware archive must include:
  369.  
  370.         WSC10.TMD  -- The WSC installation data file.  Required  for both
  371.                       shareware installation and "personal" registration.
  372.  
  373.         TRIALS.EXE -- The TRIALS executable used to install WSC4C.
  374.  
  375.   (6) TRIALS will open WSC10.TMD in order to install WSC. Type:
  376.  
  377.         TRIALS -i WSC10
  378.  
  379.   (7)  Once  installed,  WSC4C  cannot be reinstalled unless you reformat your
  380.   hard drive.  TRIALS does not modify disk formatting or employ other marginal
  381.   procedures.  TRIALS creates a configuration file which it uses to keep track
  382.   of the number of executions.  Do not modify or move this file  or  you  will
  383.   not be able to execute WSC4C programs.
  384.  
  385.   WSC4C must be installed on each computer on which WSC4C programs will run.
  386.  
  387.   (9) The installation can be tested by typing:
  388.  
  389.         TRIALS -L
  390.  
  391.   (10)  Copy  WSC.DLL,  WTMLIB.DLL  [Shareware version only], and MODEM_IO.DLL
  392.   from your work directory to the C/C++ compiler directory.  Start  C/C++  and
  393.   compile SIMPLE.MAK.
  394.  
  395.   (11)  The  recommended  way  to  test  SIMPLE  is to run it on two computers
  396.   connected by a null modem cable.  Whatever is typed on one  computer  should
  397.   be  displayed  on  the  other.  If you don't have two computers, you can use
  398.   SIMPLE to talk to your modem.  Sending an "AT" to the modem should result in
  399.   an "OK" being sent back. See Section 7.1 "SIMPLE" for more information.
  400.  
  401.   (12) Compile and link LOGIN. Use LOGIN to call a local BBS. See Section  7.2
  402.   "LOGIN" for more information.
  403.  
  404.   (13)  Compile  and  link  SELFTEST.  Use SELFTEST to test one of your serial
  405.   ports. See Section 7.3 "SELFTEST" for more information.
  406.  
  407.  
  408.  WSC4C Users Manual                                                Page 6
  409.   3.0 Library Overview
  410.  
  411.  
  412.   3.1 Dynamic Link Libraries
  413.  
  414.  
  415.   WSC4C is provided as a dynamic link library (DLL). A DLL is characterized by
  416.   the fact that it need not be loaded until required by an application program
  417.   and that only one copy of the DLL is necessary regardless of the  number  of
  418.   application  programs  that  use it. Contrast this to the traditional static
  419.   library which is bound to each and every application that uses  it  at  link
  420.   time.
  421.  
  422.   Since  WSC4C is a DLL, only one copy of the WSC4C code & data is loaded into
  423.   memory regardless of the number of applications programs that use it.
  424.  
  425.   For example, more than one instance  of  the  test  program  SIMPLE  can  be
  426.   started.   All  copies of SIMPLE can run concurrently as long as each uses a
  427.   different COM port.
  428.  
  429.  
  430.   3.2 Using the Library
  431.  
  432.  
  433.   The WSC4C has been tested on a Gateway 2000 25 MHZ 80386-DX, a Gateway 2000
  434.   66MHZ  80486-DX2  (all  running  Windows  3.1),  and a Mid-West Micro 150MHZ
  435.   Pentium running Windows 95.
  436.  
  437.   WSC4C has also been tested with Microsoft C/C++ 7.0 (from the Windows  SDK),
  438.   Microsoft Visual C/C++, Borland C/C++, and Watcom C/C++.
  439.  
  440.   Please examine the WSC4C.H file. Note that COM1 is defined as port zero, not
  441.   port  one.   The  user must assume the responsibilty for passing the correct
  442.   information when calling WSC4C functions.
  443.  
  444.   We recommend that you experiment with the four example programs.
  445.  
  446.  
  447.   3.3 Compiling Programs
  448.  
  449.  
  450.   The  example programs can be compiled by either using the provided MAKEFILES
  451.   or creating a project file for the IDE. The next two sections  provide  more
  452.   detail for each of these alternatives.
  453.  
  454.  
  455.   3.4 Using a MAKEFILE
  456.  
  457.  
  458.   Makefiles  originated  on UNIX systems. They are the standard way that C/C++
  459.   programs are constructed in command line environments. Windows programs  can
  460.   be  constructed  with  makefiles  running  DOS  using  command  line Windows
  461.   compilers, such as provided by Watcom, Borland and Microsoft.
  462.  
  463.   Makefiles  are  provided  for  Microsoft,  Borland,  amd WATCOM command line
  464.   compilers. Makefiles have file extensions of "_M_" for Microsoft, "_B_"  for
  465.   Borland,  and  "_W_" for WATCOM. Thus, SIMPLE._W_ is the makefile for SIMPLE
  466.   when using the WATCOM compiler.
  467.  
  468.  
  469.  
  470.  
  471.  
  472.  
  473.  
  474.  
  475.  
  476.  WSC4C Users Manual                                                Page 7
  477.   3.5 Using an IDE
  478.  
  479.  
  480.   All windows compilers have an Integrated Development Environment  (IDE)  for
  481.   building  application programs in the Windows environment. Since there is no
  482.   standard format for IDE project files, file names must be entered  into  the
  483.   IDE  from  the  keyboard.  Each example program has a project text file (eg:
  484.   SIMPLE.PRJ) which contains the list of filenames that must be  entered  into
  485.   the IDE.
  486.  
  487.   The  example  programs  have been build using Microsoft, Borland, and Watcom
  488.   IDEs. Refer to IDE_INFO.DOC for more information on using specfic IDEs.
  489.  
  490.  
  491.   3.6 Compiling WSC
  492.  
  493.  
  494.   Registered  users  (commercial  version  only)  can  compile WSC in order to
  495.   create WSC.DLL. Makefiles are provided for each compiler.
  496.  
  497.   For Microsoft C, type:
  498.  
  499.       NMAKE WSC4C._M_
  500.  
  501.   For Borland C, type:
  502.  
  503.       MAKER -fWSC4C._B_
  504.  
  505.   For Watcom C, type:
  506.  
  507.       WMAKE -f WSC4C._W_
  508.  
  509.  
  510.  
  511.  
  512.  
  513.  
  514.  
  515.  
  516.  
  517.  
  518.  
  519.  
  520.  
  521.  
  522.  
  523.  
  524.  
  525.  
  526.  
  527.  
  528.  
  529.  
  530.  
  531.  
  532.  
  533.  
  534.  
  535.  
  536.  
  537.  
  538.  
  539.  
  540.  
  541.  
  542.  
  543.  
  544.  WSC4C Users Manual                                                Page 8
  545.   4.0 Talking to Your Modem
  546.  
  547.  
  548.   A modem is used to extend the  distance  over  which  you  may  communicate.
  549.   Without  a  modem, your RS232 cable is limited to a maximum of approximately
  550.   50 feet.  But with a modem, you can communicate literally around the world.
  551.  
  552.  
  553.   4.1 Modem Standards
  554.  
  555.  
  556.   Two modems can communicate over a telephone line only if they are both using
  557.   the same signaling frequencies and modulation, which are determined  by  the
  558.   the  modem  standards used.  Modem standards can be divided into three sets:
  559.   (1) speed, (2) data compression used, and (3) error control.
  560.  
  561.   The Bell standards  (103  &  212A)  are  those  of  AT&T.   The  CCITT  (The
  562.   International  Consultative Committee for Telephone and Telegraph) standards
  563.   are designated as "V. ".
  564.  
  565.  
  566.   Speed
  567.  
  568.  
  569.        Bell 103  :   300 baud
  570.        Bell 212A :  1200 baud
  571.        V.21      :   300 baud
  572.        V.22bis   :  1200 & 2400 baud
  573.        V.32      :  4800 & 9600 baud
  574.        V.32bis   :  4800, 7200, 9600, 12000, and 14400 baud
  575.        V.34      :  to 28800 baud.
  576.  
  577.   Data Compression
  578.  
  579.  
  580.        MNP 5     :  Microcom Networking Protocol (proprietary).
  581.        V.42bis   :  International data compression standard.
  582.  
  583.  
  584.   Error Control
  585.  
  586.  
  587.        MNP 2,3,4 :  Three level error correction (public domain).
  588.        V.42      :  International error correction standard.
  589.  
  590.  
  591.  
  592.  
  593.  
  594.  
  595.  
  596.  
  597.  
  598.  
  599.  
  600.  
  601.  
  602.  
  603.  
  604.  
  605.  
  606.  
  607.  
  608.  
  609.  
  610.  
  611.  
  612.  WSC4C Users Manual                                                Page 9
  613.   4.2 Flow Control
  614.  
  615.  
  616.   With modems using data compression, the modem to modem connection  will  run
  617.   at  various  speeds  depending  on the quality of the line.  The computer to
  618.   modem connection will be at a fixed baud rate. Therefore, a  protocol  (flow
  619.   control)  is  necessary to synchronize the data flow between a modem and the
  620.   computer to  which  it  is  connected.   Refer  to  your  modem  manual  for
  621.   information on flow control protocols supported.
  622.  
  623.   Two  flow  control  protocols are used by most all modems which require flow
  624.   control.  Software flow control is called "XON/XOFF"  (other  software  flow
  625.   control  character  pairs  are defined but operate the same as XON/XOFF) and
  626.   hardware flow control is called "RTS/CTS".  Most modems which  require  flow
  627.   control enable hardware flow control by default.
  628.  
  629.   In XON/XOFF (software) flow control, the computer suspends transmitting data
  630.   if  it  receives  a  XOFF  character  (13 hex) from the modem, and continues
  631.   transmitting when it receives a XON character  (11  hex).   Similiarly,  the
  632.   computer  can  signal  the modem not to send any more data by transmitting a
  633.   XOFF to it, and can tell the modem to continue  transmission  be  sending  a
  634.   XON.
  635.  
  636.   In RTS/CTS (hardware) flow control, the RTS line is used by the computer  to
  637.   signal  the  modem  ,  while the CTS line is used by the modem to signal the
  638.   computer.  The RTS line is set OFF by the computer  to  tell  the  modem  to
  639.   suspend  transmission,  and  set  to  ON  to  tell  the  modem  to  continue
  640.   transmission.  The CTS line is set to OFF by the modem to tell the  computer
  641.   to  stop  transmitting,  and  set  to  ON  to  tell the computer to continue
  642.   transmitting.
  643.  
  644.   Given  the  choice,  always  choose hardware flow control over software flow
  645.   control so that all data transmission  is  transparent.   If  hardware  flow
  646.   control  is  not  the default (which it almost always is), you should modify
  647.   your modem initialization string to turn hardware flow control on.
  648.  
  649.   WSC4C supports both hardware  and  software  flow  control.   Refer  to  the
  650.   SioFlow function in the WSC4C Reference Manual.
  651.  
  652.  
  653.  
  654.  
  655.  
  656.  
  657.  
  658.  
  659.  
  660.  
  661.  
  662.  
  663.  
  664.  
  665.  
  666.  
  667.  
  668.  
  669.  
  670.  
  671.  
  672.  
  673.  
  674.  
  675.  
  676.  
  677.  
  678.  
  679.  
  680.  WSC4C Users Manual                                                Page 10
  681.   4.3 MODEM I/O (MIO)
  682.  
  683.   4.3.1 MIO Introduction
  684.  
  685.   The file MODEM_IO.C contains declarations for using the Modem I/O DLL. These
  686.   functions  ease  communicating  with  modems  using  AT commands.  The LOGIN
  687.   example program code has examples of using the MIO functions.
  688.  
  689.   The Windows "operating system" is what is called "cooperative multitasking".
  690.   This means that the  executing  Windows  task  must  voluntarily  "give  up"
  691.   control before another Windows task (or Windows itself) can execute.
  692.  
  693.   The  difficulty  is  how  to  wait  for  a  number  of  seconds  while still
  694.   relinquishing control periodically before the wait is up. One solution is by
  695.   making functions that need to wait (such as the MIO functions) into  "state"
  696.   machines. A function is broken down into parts called states, and control is
  697.   returned to Windows between executing each state.
  698.  
  699.   For example, to send the string "ATDT1,205,880,9748" to the modem  with  one
  700.   tenth second delay between transmitted characters, the following sequence is
  701.   used:
  702.  
  703.   (1) Send the string to the MIO driver by executing:
  704.  
  705.   Code = mioSendTo(Port,100,"!ATDT1,205,880,9748")
  706.  
  707.   The '!' characters are converted to carriage returns.  The  text  string  is
  708.   copied into the driver's data area.
  709.  
  710.   (2)  Call mioDriver (typically based on a timer) until MIO_IDLE is returned.
  711.   Each time mioDriver is called, it will send another character to  the  modem
  712.   provided  the  required  delay  (since  the previous character was sent) has
  713.   passed.  If the delay has not passed, the driver simply returns MIO_RUNNING,
  714.   but without actually sending a character to the modem.  Once all  characters
  715.   have been sent, mioDriver will return MIO_IDLE, indicating it is done and is
  716.   ready to accept another function.
  717.  
  718.   mioDriver  will return MIO_RUNNING if it is still processing.  Anything else
  719.   received indicates that it is still processing and the returned value  is  a
  720.   character from the modem that can be displayed if wanted.
  721.  
  722.   (3) Once mioDriver returns MIO_IDLE, call mioResult to get the result of the
  723.   mioSendTo call.
  724.  
  725.   The above is rather straight forward in practice.  See the LOGIN application
  726.   for an example of its use.
  727.  
  728.  
  729.   4.3.2 MIO Functions
  730.  
  731.   4.3.2.1 mioDriver
  732.  
  733.   Syntax: int mioDriver(int Port)
  734.  
  735.   mioDriver  executes  the  next  state of any previously started MIO function
  736.   such as mioSendTo, mioWaitFor, and mioQuiet. It returns:
  737.  
  738.   MIO_IDLE    : if the driver is ready for the next mioSendTo, mioWaitFor, or
  739.                 mioQuiet.
  740.   MIO_RUNNING : if the driver is not idle.
  741.   <otherwise> : if the driver is not idle,  and  the  returned  character  was
  742.                 received from the modem.
  743.  
  744.  
  745.  
  746.  
  747.  
  748.  WSC4C Users Manual                                                Page 11
  749.   4.3.2.2 mioBreak
  750.  
  751.   Forces the MIO driver to the IDLE state, abandoning any work in progress.
  752.  
  753.  
  754.   4.3.2.3 mioSendTo
  755.  
  756.   Syntax:  int mioSendTo(int Port, long Pace, char *String)
  757.  
  758.   The mioSendTo function sends the characters in the string 'Text'  to  serial
  759.   output. There is a delay of 'Pace' milliseconds between characters.
  760.  
  761.  
  762.   4.3.2.4 mioWaitFor
  763.  
  764.   Syntax: int mioWaitFor(int Port, long Wait, int Case, char *String)
  765.  
  766.   The  mioWaitFor  function  waits for characters from serial input that match
  767.   the string 'Text'. A total of 'Wait' milliseconds are allowed before  timing
  768.   out  and  returning  FALSE (0).  If the 'Case' flag is TRUE, then the string
  769.   comparison is NOT case sensitive.
  770.  
  771.   For example, to wait up to one minute for "CONNECT", "NO CARRIER", or "BUSY"
  772.   from the modem after dialing a number (on COM1):
  773.  
  774.   Code = mioWaitFor(COM1,60000,1,"CONNECT|NO CARRIER|BUSY")
  775.  
  776.   The function mioDriver() must be called until MIO_IDLE  is  returned.   Then
  777.   mioResult()  is  called  to  get the result of the mioWaitFor.  A value of 0
  778.   indicates  that  neither "CONNECT", "BUSY", nor "NO CARRIER" was received. A
  779.   non-zero value indicates that one of the three sub-strings was received.   A
  780.   ASC("0")  is  returned  if  "CONNECT"  was seen, ASC("1") is returned if "NO
  781.   CARRIER" was seen, and ASC("2") is returned if "BUSY" was seen.
  782.  
  783.  
  784.   4.3.2.5 mioQuiet
  785.  
  786.   Syntax: int mioQuiet(int Port,long Wait)
  787.  
  788.   The mioQuiet function waits for continuous quiet [no incoming  serial  data]
  789.   of  'Wait'  milliseconds  before  returning.   Any  incoming character while
  790.   mioQuiet is running is flushed.
  791.  
  792.  
  793.   4.3.3 MIO Summary
  794.  
  795.    mioDriver : Allows the execution of mioSendTo, mioWaitFor, or mioQuiet once
  796.                they   have   been   started.   Returns  MIO_IDLE  (defined  in
  797.                MODEM_IO.C) if ready not running, MIO_RUNNING if running, and
  798.                anything else is  a  character  from  the  modem  that  can  be
  799.                displayed if wanted.
  800.  
  801.     mioBreak : Forces the  MIO  driver to IDLE state.
  802.  
  803.    mioSendTo : Sends a string (including control chars) to the modem.
  804.  
  805.   mioWaitFor : Waits  for a particular string from the modem, passing all else
  806.                through.
  807.  
  808.     mioQuiet : Waits for continuous  quiet  of  a specified duration.
  809.  
  810.     mioBreak : Breaks further modem I/O activity.
  811.  
  812.  
  813.  
  814.  
  815.  
  816.  WSC4C Users Manual                                                Page 12
  817.   4.4 Modem Initialization
  818.  
  819.  
  820.   If  your  application uses a modem (as opposed to using a null modem cable),
  821.   then you should always send an initialization string to your modem if it  is
  822.   a  programmable  modem  such as those made by Hayes.  Communication programs
  823.   such as PROCOMM and TELIX always send such a string automatically as soon as
  824.   they start up.
  825.  
  826.   The particular initialization string depends on the make of your modem.  For
  827.   Hayes and Hayes AT command  set  compatible  modems,  the  following  string
  828.   (followed by a carriage return) should work:
  829.  
  830.        AT E1 S7=60 S11=60 V1 X1 Q0 S0=0
  831.  
  832.   Refer to your Modem User's Guide for a full discussion of these commands.  A
  833.   brief description is as follows:
  834.  
  835.        AT     Modem attention command.
  836.        E1     Modem will echo what you send to it.
  837.        S7=60  Wait 60 seconds for carrier and/or dial tone.
  838.        S11=60 Use 60 milliseconds for tone dialing duration & spacing.
  839.        V1     Display result code as words (not numbers).
  840.        X1     Use the extended result message (CONNECT XXXX) set.
  841.        Q0     Modem returns result codes.
  842.        S0=0   Do not answer RING.
  843.  
  844.   If  your application will answer incoming calls, then set the S0 register to
  845.   the ring on which to automatically answer.
  846.  
  847.   If you send the above codes by using SioPutc (as opposed to typing them from
  848.   the keyboard), then follow these guidelines:
  849.  
  850.   (1) Send an initial carriage return before the initialization string.
  851.  
  852.   (2) Pause at least 150 milliseconds after each character sent as your  modem
  853.   needs the time to perform its own internal processing. Pause a little longer
  854.   if your modem is not accepting your initialization string.
  855.  
  856.   (3)  Pause  one  and a half seconds after sending any initialization command
  857.   such as ATZ or AT&F since your modem must do quite a bit of processing.
  858.  
  859.   If you experience any problems in initializing your Hayes modem, you  should
  860.   first reset it to factory settings by sending:
  861.  
  862.        AT&F
  863.  
  864.   Refer  to the LOGIN program (function SendToModem is in the file MODEM_IO.C)
  865.   for an example of sending an initialization string  to  a  Hayes  compatible
  866.   modem.
  867.  
  868.  
  869.  
  870.  
  871.  
  872.  
  873.  
  874.  
  875.  
  876.  
  877.  
  878.  
  879.  
  880.  
  881.  
  882.  
  883.  
  884.  WSC4C Users Manual                                                Page 13
  885.   5.0 Problems
  886.  
  887.  
  888.   If  you  cannot  get your application to run properly, first compile and run
  889.   the terminal emulator program SIMPLE provided  on  your  distribution  disk.
  890.   Test  SIMPLE  by  connecting  two  computers  with  a null modem cable or by
  891.   commanding a Hayes AT command set compatible modem.
  892.  
  893.   Once  SIMPLE  runs, compile and run the SELFTEST program.  This program will
  894.   test your serial ports' functionality.
  895.  
  896.   If your application does not run but SIMPLE and SELFTEST run correctly, then
  897.   you  have  most  likely  made  a  programming  mistake  in your application.
  898.   MarshallSoft Computing cannot debug your application,  especially  over  the
  899.   telephone!   However,  consider  each of the following when searching for an
  900.   error in your application.
  901.  
  902.   1.  Have you included the file WSC4C.H in your application ?
  903.  
  904.   2.  Is your receive buffer large enough ? Use a receive buffer size that  is
  905.   twice the size of the largest expected incoming block.
  906.  
  907.   3.  Have you selected too high a baud rate? Windows can multitask many tasks
  908.   at once. You may have to lower your baud rate (or get 16550 UARTS).
  909.  
  910.   4.  Did SioReset return a zero value ?  If not, then you must call  SioReset
  911.   again. See SIMPLE.C for an example.
  912.  
  913.   5.   Did  you  send the proper initialization string to your modem ? Did you
  914.   set DTR and RTS ? (you should).
  915.  
  916.   7.  Do you have more than one COM1 port?  For example, if you  have  a  COM1
  917.   port  on  your  motherboard, you cannot add another COM1 port or modem board
  918.   that uses COM1 without first disabling the COM1 on the motherboard.
  919.  
  920.   We recommend the following steps if you believe that you have  discovered  a
  921.   bug in the library: (1) Create the smallest, simpliest test program possible
  922.   that   demonstrates   the   problem.    (2)   Document  your  exact  machine
  923.   configuration and what error the test program demonstrates.  (3) Upload  the
  924.   example source to our user support BBS, email it or mail us a disk.
  925.  
  926.   If  the  problem can be solved with an easy work-around, we will publish the
  927.   work-around.  If the problem requires a modification to the library, we will
  928.   make the change and make the modified library  available  to  our  customers
  929.   without charge.
  930.  
  931.  
  932.  
  933.  
  934.  
  935.  
  936.  
  937.  
  938.  
  939.  
  940.  
  941.  
  942.  
  943.  
  944.  
  945.  
  946.  
  947.  
  948.  
  949.  
  950.  
  951.  
  952.  WSC4C Users Manual                                                Page 14
  953.   6.0 Serial Communications
  954.  
  955.   6.1 Communications Basics
  956.  
  957.  
  958.   The  heart  of  serial  communications  is  the UART (Universal Asynchronous
  959.   Receiver Transmitter).  The IBM  PC/XT/AT  and  compatibles  use  the  8250,
  960.   16450, or the 16550 UART.  The purpose of the UART is:
  961.  
  962.   (1) To convert bytes from the CPU (Central Processing Unit), into  a  serial
  963.   format  by  adding  the  necessary start, stop, and parity bits to each byte
  964.   before transmission, and to then transmit each bit at the correct baud rate.
  965.  
  966.   (2) To convert the incoming stream (at a specified baud rate) of serial bits
  967.   into bytes by removing the start, stop, and parity bits  before  being  made
  968.   available to the CPU.
  969.  
  970.   The  UART  is part of the serial interface circuitry which allows the CPU to
  971.   send and receive signals over the RS232 lines. This  can  be  diagrammed  as
  972.   follows:
  973.  
  974.  
  975.  
  976.                         Serial Interface
  977.                      +-------------------+
  978.                      |                   |
  979.   +-----+  Data Bus  |     +------+      |    RS232 Signals
  980.   | CPU +------------+     | UART |      +----------------*
  981.   +-----+            |     +------+      |
  982.                      |                   |
  983.                      +-------------------+
  984.  
  985.  
  986.  
  987.   The 8250/16450/16550 UART is capable of  operating  in  one  of  two  modes,
  988.   "polled" and "interrupt driven".  The serial communications functions in the
  989.   BIOS  use  the  polled  method.  In this approach, the CPU is typically in a
  990.   loop asking the UART over and over again if it has  a  byte  ready.  If  its
  991.   does,  the  polling  code  returns the byte.  But, if the next byte comes in
  992.   before the polling code is executing again, then that byte is lost.
  993.  
  994.   In the interrupt driven approach (used by Windows/WSC4C), when  a  byte  is
  995.   received  by  the  UART,  an  "Interrupt  Service Routine" (ISR) is executed
  996.   immediately, suspending temporarily whatever else is executing. The ISR then
  997.   moves the byte to a buffer so that your application program can  later  read
  998.   it.
  999.  
  1000.   Transmitted  bytes are queued up awaiting  transmission.   When  a  byte  is
  1001.   moved  from  the  UART  transmitter holding register to the UART transmitter
  1002.   shift register, an interrupt is generated and the next byte  is  taken  from
  1003.   the  library  transmitter  buffer by the ISR and written to the UART holding
  1004.   register.
  1005.  
  1006.   Up to 16 bytes can be taken from the transmitter buffer while processing one
  1007.   transmitter  interrupt  if an 16550 UART is used. The 16550 UART is strongly
  1008.   recommended for computers doing serial communications under Windows.
  1009.  
  1010.   Additional information on serial port hardware can be found  in  the  User's
  1011.   manual for our companion product PCL4W.
  1012.  
  1013.  
  1014.  
  1015.  
  1016.  
  1017.  
  1018.  
  1019.  
  1020.  WSC4C Users Manual                                                Page 15
  1021.   6.2 RS-232 Signals
  1022.  
  1023.  
  1024.   RS-232 is the name of the serial data interface  standard  used  to  connect
  1025.   computers  to modems.  Most IBM compatible computers are built with at least
  1026.   one serial port and use either DB9 (9 pin) or DB25 (25 pin) connectors.
  1027.  
  1028.   A summary of these pins and  their  function  follows.   For  more  detailed
  1029.   information, refer to one of the many books dealing with RS-232 interfacing.
  1030.  
  1031.   Signal Ground Pin 7 (DB25), Pin 5 (DB9)
  1032.  
  1033.   The  SG  line  is  used  as  the  common  signal  ground, and must always be
  1034.   connected.
  1035.  
  1036.   Transmit Data Pin 2 (DB25), Pin 3 (DB9)
  1037.  
  1038.   The TX line is used to carry data from the computer to the modem.
  1039.  
  1040.   Receive Data Pin 3 (DB25), Pin 2 (DB9)
  1041.  
  1042.   The RX line is used to carry data from the modem to the computer.
  1043.  
  1044.   Data Terminal Ready Pin 20 (DB25), Pin 4 (DB9)
  1045.  
  1046.   The DTR line is used by the computer to signal the modem that it  is  ready.
  1047.   DTR should be set high when talking to a modem.
  1048.  
  1049.   Data Set Ready Pin 6 (DB25), Pin 6 (DB9)
  1050.  
  1051.   The DSR line is used by the modem to signal the computer that it is ready.
  1052.  
  1053.   Request to Send Pin 4 (DB25), Pin 7 (DB9)
  1054.  
  1055.   The  RTS  line  is used to "turn the line around" in half duplex modems, and
  1056.   for hardware flow control in most modems that require flow control.  RTS  is
  1057.   controlled by the computer and read by the serial device (modem).
  1058.  
  1059.   Clear to Send Pin 5 (DB25), Pin 8 (DB9)
  1060.  
  1061.   The  CTS  line  is used to "turn the line around" in half duplex modems, and
  1062.   for hardware flow control in most modems that require flow control.  CTS  is
  1063.   controlled by the serial device (modem) and read by the computer.
  1064.  
  1065.   Data Carrier Detect Pin 8 (DB25), Pin 1 (DB9)
  1066.  
  1067.   The DCD line is used by the modem to signal the computer that a data carrier
  1068.   signal is present.
  1069.  
  1070.   Ring Indicator Pin 22 (DB25), Pin 9 (DB9)
  1071.  
  1072.   The RI line is asserted when a 'ring' occurs.
  1073.  
  1074.  
  1075.  
  1076.  
  1077.  
  1078.  
  1079.  
  1080.  
  1081.  
  1082.  
  1083.  
  1084.  
  1085.  
  1086.  
  1087.  
  1088.  WSC4C Users Manual                                                Page 16
  1089.   7.0 Example Programs
  1090.  
  1091.  
  1092.   7.1 SIMPLE
  1093.  
  1094.  
  1095.   SIMPLE   is  a  very  simple  communications   programming   using   WSC4C.
  1096.   Everything  that  is  typed  on the keyboard is sent to the serial port, and
  1097.   everthing incoming from the serial port is displayed on the screen.
  1098.  
  1099.   The easiest way to test SIMPLE is to connect to a modem.  Typing "AT" should
  1100.   result in an "OK" being displayed.
  1101.  
  1102.   A  null-modem  cable can also be used to connect two computers together with
  1103.   their serial ports. Run SIMPLE on both machines. Whatever is  typed  on  one
  1104.   machine will be displayed on the other.
  1105.  
  1106.  
  1107.   7.2 LOGIN
  1108.  
  1109.  
  1110.   LOGIN  is the same program as SIMPLE but with the addition of "Modem" on the
  1111.   menu bar.  Under "Modem", select "Start", then "Handshake" in order to  send
  1112.   an "AT" to the connected modem, or "Dial" to send a dial string to the modem
  1113.   (which  dials  our  user  support  BBS). Once the dial sequence is sent, the
  1114.   program will wait for up to 60 seconds for the  "CONNECT"  string  from  the
  1115.   modem.  This  wait  can  be terminated at any time by choosing "BREAK" under
  1116.   "Modem".
  1117.  
  1118.   To  test LOGIN, you need a AT command set compatible modem and a BBS to call
  1119.   up. LOGIN will dial our BBS at 205-880-9748, or  edit  the  dial  string  in
  1120.   LINE.C to call up a local BBS.
  1121.  
  1122.  
  1123.   7.3 SELFTEST
  1124.  
  1125.  
  1126.   SELFTEST  performs  a  serial port I/O functionality test.  Either a pair of
  1127.   ports on the same computer (using a null  modem  cable)  or  a  single  port
  1128.   (using a loopback adapter) can be tested.
  1129.  
  1130.   Refer  to  LOOPBACK.DOC for an explanation of how to make a loopback adapter
  1131.   (without tools!).
  1132.  
  1133.  
  1134.   7.4 RS232
  1135.  
  1136.  
  1137.   RS232 is similiar to SELFTEST, but with enhanced capability. It can set flow
  1138.   control  (hardware,  software,  or  none), DTR line (set or clear), RTS line
  1139.   (set or clear), display the transmit & receive queue sizes, detect  a  break
  1140.   signal,  detect  changes  in  DSR and CTS, as well as check for various line
  1141.   errors (parity error, framing error, data overrun, receive  queue  overflow,
  1142.   transmit buffer full).
  1143.  
  1144.  
  1145.  
  1146.  
  1147.  
  1148.  
  1149.  
  1150.  
  1151.  
  1152.  
  1153.  
  1154.  
  1155.  
  1156.  WSC4C Users Manual                                                Page 17
  1157.  
  1158.   8.0 Legal Issues
  1159.  
  1160.   8.1 Registration
  1161.  
  1162.   Two types of registration are provided, (1) Personal and (2) Commercial.
  1163.  
  1164.   (1)  Personal  Registration  is for personal (non-commercial) use of WSC4C.
  1165.   The registration fee is $39.95. To register, type (from the  DOS  prompt  in
  1166.   the work directory containing WSC10.TMD) :
  1167.  
  1168.        TRIALS -k WSC10
  1169.  
  1170.   The TRIALS program will prompt you for your name, then display three control
  1171.   codes.  You  then  contact  us by phone, mail, email or BBS. We will need to
  1172.   know the exact (case sensitive) name typed into TRIALS as well as the  exact
  1173.   control codes displayed.
  1174.  
  1175.   After  receiving payment, you will be issued an authorization code which you
  1176.   enter into the TRIALS program, which will generate C:\WSC10.KEY.
  1177.  
  1178.   You  can  re-run  TRIALS  to  generate  the  key  file  once  you  have  the
  1179.   authorization code. However, you must run TRIALS on  the  same  machine  the
  1180.   second time in order to get the same control codes.
  1181.  
  1182.   Once WSC10.KEY is created, it can be copied to any machine on which you will
  1183.   use WSC.
  1184.  
  1185.   Personal  registration  does  not include printed manuals or disks.  Printed
  1186.   manuals (they are on the distribution archive) can be ordered  for  $10  per
  1187.   set plus $5 S&H (or $10 S&H outside of North America).
  1188.  
  1189.   (2) Commercial Registration costs $74.95 and includes complete source  code,
  1190.   printed  manuals, no shareware screen of any kind displayed, and no key file
  1191.   required.  A registered archive will be mailed along with printed manuals.
  1192.  
  1193.   To order, contact us as shown on the title page of this manual.
  1194.  
  1195.   Multiple copy discounts (3 or more) and site licenses are available.  Please
  1196.   call for details.
  1197.  
  1198.   We accept American Express, VISA, MasterCard, checks in US dollars drawn  on
  1199.   a  US  bank,  International  Postal Money Orders, purchase orders (POs) from
  1200.   recognized US schools and companies listed in  Dun  &  Bradstreet,  and  COD
  1201.   (street  address and phone number required) within the USA (plus a $4.50 COD
  1202.   charge).
  1203.  
  1204.   For credit  card  orders,  be  sure  to  include  the  account  number,  the
  1205.   expiration  date,  the exact name on the card, and the complete card billing
  1206.   address (the address to which the credit card bill is mailed).
  1207.  
  1208.  
  1209.  
  1210.  
  1211.  
  1212.  
  1213.  
  1214.  
  1215.  
  1216.  
  1217.  
  1218.  
  1219.  
  1220.  
  1221.  
  1222.  
  1223.  
  1224.  WSC4C Users Manual                                                Page 18
  1225.   8.1 Registration (continued)
  1226.  
  1227.   Print the file WSC4C.INV if an invoice is needed.
  1228.  
  1229.   If  you  wish to update from an older version of WSC4C, send $25 plus $5 S&H
  1230.   ($10 S&H outside of North America).
  1231.  
  1232.   The commercial registered package includes:
  1233.  
  1234.        o  WSC4C Library w/o shareware screens.
  1235.        o  C/C++ source code for WSC and MODEM_IO.
  1236.        o  Laser printed Users Manual & Reference Manual.
  1237.        o  Telephone, BBS, and email support for one year.
  1238.  
  1239.   The registered user will receive the latest version of WSC4C shipped  by  US
  1240.   second  day  priority  mail  (packet  airmail overseas).  A 3.5" diskette is
  1241.   provided unless a 5.25" diskette is requested.
  1242.  
  1243.   All prices are guaranteed for one year from the release date as  printed  on
  1244.   the title page.
  1245.  
  1246.  
  1247.   8.2 License
  1248.  
  1249.  
  1250.   MarshallSoft  Computing,  Inc. grants the registered user of WSC4C the right
  1251.   to use one copy of the WSC4C library (in object form) on a  single  computer
  1252.   in  the  development  of  any software product (other than libraries such as
  1253.   WSC4C).  The user may not use the library on more than one computer  at  the
  1254.   same  time.   The  source  code  for  the  library (WSC.C) is copyrighted by
  1255.   MarshallSoft Computing and may not be released in whole or in part. Products
  1256.   developed using WSC4C may be distributed without any royalty.
  1257.  
  1258.  
  1259.   8.3 Warranty
  1260.  
  1261.  
  1262.   MARSHALLSOFT COMPUTING, INC.  DISCLAIMS  ALL  WARRANTIES  RELATING  TO  THIS
  1263.   SOFTWARE,  WHETHER  EXPRESSED  OR  IMPLIED, INCLUDING BUT NOT LIMITED TO ANY
  1264.   IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR  PURPOSE,
  1265.   AND  ALL  SUCH WARRANTIES ARE EXPRESSLY AND SPECIFICALLY DISCLAIMED. NEITHER
  1266.   MARSHALLSOFT COMPUTING, INC. NOR ANYONE ELSE WHO HAS BEEN  INVOLVED  IN  THE
  1267.   CREATION,  PRODUCTION,  OR DELIVERY OF THIS SOFTWARE SHALL BE LIABLE FOR ANY
  1268.   INDIRECT, CONSEQUENTIAL, OR INCIDENTAL DAMAGES ARISING OUT  OF  THE  USE  OR
  1269.   INABILITY  TO  USE  SUCH  SOFTWARE EVEN IF MARSHALLSOFT COMPUTING, INC.  HAS
  1270.   BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES OR CLAIMS. IN NO EVENT SHALL
  1271.   MARSHALLSOFT COMPUTING, INC.'S LIABILITY FOR ANY SUCH  DAMAGES  EVER  EXCEED
  1272.   THE  PRICE  PAID FOR THE LICENSE TO USE THE SOFTWARE, REGARDLESS OF THE FORM
  1273.   OF THE CLAIM. THE PERSON USING THE SOFTWARE BEARS ALL RISK AS TO THE QUALITY
  1274.   AND PERFORMANCE OF THE SOFTWARE.
  1275.  
  1276.   Some states do not allow  the  exclusion  of  the  limit  of  liability  for
  1277.   consequential  or  incidental damages, so the above limitation may not apply
  1278.   to you.
  1279.  
  1280.   This agreement shall be governed by the laws of the  State  of  Alabama  and
  1281.   shall  inure  to  the  benefit  of  Marshallsoft  Computing,  Inc.   and any
  1282.   successors, administrators, heirs and assigns.   Any  action  or  proceeding
  1283.   brought  by either party against the other arising out of or related to this
  1284.   agreement shall be brought only in a STATE or  FEDERAL  COURT  of  competent
  1285.   jurisdiction  located in Madison County, Alabama. The parties hereby consent
  1286.   to in personam jurisdiction of said courts.
  1287.  
  1288.  
  1289.  
  1290.  
  1291.  
  1292.  WSC4C Users Manual                                                Page 19
  1293.   9.0 Summary
  1294.  
  1295.  
  1296.   9.1 Revision History
  1297.  
  1298.  
  1299.   Version 1.0: 9 September, 1996.  -  The initial release of WSC4C.
  1300.  
  1301.  
  1302.   9.2 Function Summary
  1303.  
  1304.   Refer to the WSC4C Reference Manual (WSC4C_R.DOC) for  detailed  information
  1305.   on  the  communications  and  support functions.  A one line summary of each
  1306.   function follows:
  1307.  
  1308.   +--------------+-----------------------------------------------------------+
  1309.   |  SioBaud     |  Sets the baud rate of the selected port.                 |
  1310.   |  SioBrkSig   |  Asserts, cancels, or detects BREAK signal.               |
  1311.   |  SioCTS      |  Reads the Clear to Send (CTS) modem status bit.          |
  1312.   |  SioDCD      |  Reads the Data Carrier Detect (DCD) modem status bit.    |
  1313.   |  SioDone     |  Terminates further serial processing.                    |
  1314.   |  SioDSR      |  Reads the Data Set Ready (DSR) modem status bit.         |
  1315.   |  SioDTR      |  Set, clear, or read the Data Terminal Ready (DTR) bit.   |
  1316.   |  SioFlow     |  Enables / disables hardware flow control.                |
  1317.   |  SioGetc     |  Reads the next character from the serial line.           |
  1318.   |  SioGets     |  Receives a string of characters.                         |
  1319.   |  SioInfo     |  Returns information such as library version.             |
  1320.   |  SioParms    |  Sets parity, stop bits, and word length.                 |
  1321.   |  SioPutc     |  Transmit a character over a serial line.                 |
  1322.   |  SioPuts     |  TRansmits a string of characters.                        |
  1323.   |  SioReset    |  Initialize a serial port for processing.                 |
  1324.   |  SioRI       |  Reads the Ring Indicator (RI) modem status bit.          |
  1325.   |  SioRTS      |  Sets, clears, or reads the Request to Send (RTS) line.   |
  1326.   |  SioRxClear  |  Clears the receive buffer.                               |
  1327.   |  SioRxQue    |  Returns the number of characters in the receive queue.   |
  1328.   |  SioStatus   |  Returns the serial port line status.                     |
  1329.   |  SioTxClear  |  Clears the transmit buffer.                              |
  1330.   |  SioTxQue    |  Returns the number of characters in the transmit queue.  |
  1331.   |  SioUnGetc   |  "Un-gets" (puts back) a specified character.             |
  1332.   +--------------+-----+-----------------------------------------------------+
  1333.  
  1334.  
  1335.  
  1336.  
  1337.  
  1338.  
  1339.  
  1340.  
  1341.  
  1342.  
  1343.  
  1344.  
  1345.  
  1346.  
  1347.  
  1348.  
  1349.  
  1350.  
  1351.  
  1352.  
  1353.  
  1354.  
  1355.  
  1356.  
  1357.  
  1358.  
  1359.  
  1360.  WSC4C Users Manual                                                Page 20
  1361.   9.3 Further Reading
  1362.  
  1363.  
  1364.   The  best way to learn about serial communications is to read a good book on
  1365.   the subject. Several good texts are available.  Two that I like are:
  1366.  
  1367.   (1) C Programmers's Guide to Serial Communications by  Joe  Campbell  (SAMS)
  1368.   (2) Mastering Serial Communications by Peter Gofton (SYBEX).
  1369.  
  1370.   You  may also want to get a copy of one of our communications products which
  1371.   talks  to  the  hardware  directly.  They  include  more  hardware  specific
  1372.   documentation.
  1373.  
  1374.  
  1375.   10.0 Other MarshallSoft Computing Products
  1376.  
  1377.  
  1378.   The following shareware  libraries  are  also  available  from  MarshallSoft
  1379.   Computing.
  1380.  
  1381.   10.1 The Personal Communications Library for Windows (C/C++)
  1382.  
  1383.   The Personal Communications Library for Windows (PCL4W) is a  Windows  based
  1384.   asynchronous   communications  library  designed  for  experienced  software
  1385.   developers programming in C/C++.  Unlike  WSC4C,  PCL4W  interfaces  to  the
  1386.   serial port hardware directly.  PCL4W also supports multiport boards such as
  1387.   those made by DigiBoard and BOCA.
  1388.  
  1389.   The  Personal  Communications Library for Windows (PCL4W) is available
  1390.   for $75 plus $5 S&H ($10 S&H overseas).
  1391.  
  1392.   10.2 The Personal Communications Library for C/C++ / DOS
  1393.  
  1394.   PCL4C  is  similiar  to  PCL4W except that it is designed for DOS.  Includes
  1395.   support for protected mode.
  1396.  
  1397.   10.3 Libraries for Other Languages
  1398.  
  1399.   We have communications libraries for C/C++, Turbo Pascal, Visual Basic , and
  1400.   PowerBASIC.
  1401.  
  1402.    PCL4C : C/C++, DOS [include ptotected mode].
  1403.    PCL4P : Turbo Pascal, DOS [includes protected mode].
  1404.   PCL4VB : Visual Basic, DOS.
  1405.   PCL4PB : Power Basic, DOS.
  1406.  
  1407.    PCL4W : C/C++, Windows 3.1 & Win 95, talks to hardware directly.
  1408.   PCLVBW : Visual Basic, Win 3.1 & Win 95, talks to hardware directly.
  1409.  
  1410.    WSC4C : C/C++, Win 3.1 & Win 95, uses Windows API.
  1411.   WSC4VB : Visual Basic, Win 3.1 & Win 95, uses Windows API.
  1412.    WSC4D : Borland DELPHI [Sept 96], Win 3.1 & Win 95, uses Windows API.
  1413.  
  1414.  
  1415.  
  1416.  
  1417.  
  1418.  
  1419.  
  1420.  
  1421.  
  1422.  
  1423.  
  1424.  
  1425.  
  1426.  
  1427.  
  1428.  WSC4C Users Manual                                                Page 21
  1429.